---
title: Backend Architecture
---


This is a high-level overview of the system architecture. The system is divided into two main components: the frontend and the backend. The frontend is responsible for handling user interactions and displaying the results. The backend is responsible for handling the business logic and executing the agents.

# System overview

```mermaid
flowchart LR
  U["User"] --> FE["Frontend (SPA)"]
  FE -- "HTTP/WS" --> BE["OpenHands Backend"]
  BE --> ES["EventStream"]
  BE --> ST["Storage"]
  BE --> RT["Runtime Interface"]
  BE --> LLM["LLM Providers"]

  subgraph Runtime
    direction TB
    RT --> DRT["Docker Runtime"]
    RT --> LRT["Local Runtime"]
    RT --> RRT["Remote Runtime"]
    DRT --> AES["Action Execution Server"]
    LRT --> AES
    RRT --> AES
    AES --> Bash["Bash Session"]
    AES --> Jupyter["Jupyter Plugin"]
    AES --> Browser["BrowserEnv"]
  end
```

This Overview is simplified to show the main components and their interactions. For a more detailed view of the backend architecture, see the Backend Architecture section below.

# Backend Architecture


```mermaid
classDiagram
  class Agent {
    <<abstract>>
    +sandbox_plugins: list[PluginRequirement]
  }
  class CodeActAgent {
    +tools
  }
  Agent <|-- CodeActAgent

  class EventStream
  class Observation
  class Action
  Action --> Observation
  Agent --> EventStream

  class Runtime {
    +connect()
    +send_action_for_execution()
  }
  class ActionExecutionClient {
    +_send_action_server_request()
  }
  class DockerRuntime
  class LocalRuntime
  class RemoteRuntime
  Runtime <|-- ActionExecutionClient
  ActionExecutionClient <|-- DockerRuntime
  ActionExecutionClient <|-- LocalRuntime
  ActionExecutionClient <|-- RemoteRuntime

  class ActionExecutionServer {
    +/execute_action
    +/alive
  }
  class BashSession
  class JupyterPlugin
  class BrowserEnv
  ActionExecutionServer --> BashSession
  ActionExecutionServer --> JupyterPlugin
  ActionExecutionServer --> BrowserEnv

  Agent --> Runtime
  Runtime ..> ActionExecutionServer : REST
```

<details>
  <summary>Updating this Diagram</summary>
  <div>
    We maintain architecture diagrams inline with Mermaid in this MDX.

    Guidance:
    - Edit the Mermaid blocks directly (flowchart/classDiagram).
    - Quote labels and edge text for GitHub preview compatibility.
    - Keep relationships concise and reflect stable abstractions (agents, runtime client/server, plugins).
    - Verify accuracy against code:
      - openhands/runtime/impl/action_execution/action_execution_client.py
      - openhands/runtime/impl/docker/docker_runtime.py
      - openhands/runtime/impl/local/local_runtime.py
      - openhands/runtime/action_execution_server.py
      - openhands/runtime/plugins/*
    - Build docs locally or view on GitHub to confirm diagrams render.

  </div>
</details>
